[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
V_USE()
Open/Create a Variable Length Field file (DBV)
-------------------------------------------------------------------------------
Syntax
V_USE( [<cFileName>],
[<cAlias>],
[<cNewArea>],
[<lExclusive>] ) -> nArea
Arguments
<cFileName> is the name of the file to be opened/created. A .DBV
extension is assumed if none is provided. If the file does not
exist, one will be created. If <cFileName> is omitted, any file
open in the current DBV area will be closed.
<cAlias> is a name to be associated with the DBV work area of the
file being opened. If this parameter is not passed or a "dummy"
argument is passed, the alias defaults to the DBV file name.
<cNewArea> is the word "NEW". This has the same affect as issuing
a SELECT 0 in Clipper or V_SELECT(0) in FlexFile just before
opening the file. In Clipper version 5.0, <cNewArea> has the same
effect as the NEW modifier of the USE command. If this parameter
is not specified, any DBV file open in the current DBV work area
will be closed and the <cFileName> file will be opened in its
place.
<lExclusive> is a logical expression determining the accessibility
of the file by other users in a network environment. If
<lExclusive> is (.T.) and the file is successfully opened, any
attempt by another user to V_USE() the <cFileName> file will be
denied until the file is V_CLOSED(). If this parameter is omitted,
FlexFile will attempt to open the <cFileName> file according to
the current setting of V_EXCLUSIV().
Returns
If successful, V_USE() returns the DBV area in which the file was
opened. Otherwise, it will return a -1 and set an error code which
may be fetched with V_ERROR(). (See appendix B for a list of error
codes.)
Description
V_USE() opens (or creates if the file does not exist) a file that
can store variable length data. Any file which is already open in
the DBV area is closed before the <cFileName> file is opened.
Although it is far more flexible, using a DBV file is very similar
to using memo-fields and a DBT file. It is not required but highly
recommended that you have a DBF file open simultaneously with the
DBV file. You will then store pointers in fields of the DBF file
that point to variable length data in the DBV file. The fields in
the DBF file cannot be defined as a <memo> fields but have the
same basic functionality.
Unlike the DBT file, FlexFile supports one to one, one to many,
and many to many relationships between the DBF field pointers and
the DBV files. For example, a system could use one DBV file to
store all its help text, random memo's, screens and arrays. The
pointers to all this data could be stored in several different DBF
files. Likewise, one DBF file may point into several DBV files. It
is left up to the programmer to keep straight which DBF fields
relate to which DBV files. (Note: it is a critical error to use a
pointer which points into one DBV file as a pointer into a
different DBV file.)
If a DBV file is opened exclusively in a network environment, no
other users may access the file until it is V_CLOSED(). Likewise,
if the file is currently being used exclusively by another user,
attempts to V_USE() that file will fail. V_USE() returns -1 if
the file is not opened and reports the error which can be fetched
with V_ERROR(). (See appendix B for a list of error codes.)
If the file is opened non-exclusively, other users may access the
variable length data simultaneously. However, because all data in
a DBV file must be accessed by a pointer which will usually be
stored in a DBF file, using standard Clipper locking procedures to
protect the DBF record will protect the variable length data
exactly as it does any field in the DBF. (See the V_REPLACE()
function for more on locking.)
Notes
. V_USE() obeys neither the SET DEFAULT nor the SET PATH
settings. Instead, it will use the current DOS default directory
or any valid path specified as a part of <cFileName>.
. Remember that your maximum number of open files must be set by
the V_FILES() function before V_USE()ing your first DBV file. The
valid DBV areas will then be from 1 to the value you passed to
V_FILES(). See V_FILES() for more on defining the active number of
files.
. Opening the same DBV file in two work areas simultaneously is
possible, however, don't do it.
. Do not confuse Clipper's selected work area with FlexFile's;
they are mutually exclusive. For example, you can have a DBF file
open in area 2 and simultaneously have a DBV file open in
V_SELECT() == 2. Likewise, Clipper's SELECT <n> has no effect on
the currently selected DBV area.
Examples
// Assume that no files are open at this point.
// Set the maximum number of files to three.
#define EXCLUSIVE_ (.T.)
V_FILES( 3 )
// Open a DBV file with an alias of "MAIN_FILE" in area 1.
// If dbv_file.dbv does not exist it will be created.
V_SELECT(1)
V_USE( "dbv_file", "MAIN_FILE" )
? V_ALIAS() // Result: MAIN_FILE
// Open another file in the next available area.
V_USE( "second", , "NEW" )
? V_SELECT() // Result: 2
// Open a third file for use on a network and test to
// make certain that the file was properly opened.
IF V_USE( "F:\GEN\JUNK\third", , "new", !EXCLUSIVE_ ) == -1
? "Error: " + str( V_ERROR(), 4 )
QUIT
ENDIF
// Close all files.
V_CLOSE( 1 ) // Closes file in area 1
V_CLOSEALL() // Closes the other two files.
See Also:
V_CLOSE()
V_SELECT()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson